<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="cgi-security.html" />
<link rel="prev" href="node561.html" />
<link rel="parent" href="module-cgi.html" />
<link rel="next" href="cgi-security.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>18.2.5 Functions</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="18.2.4 old classes"
  href="node561.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="18.2 cgi  "
  href="module-cgi.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="18.2.6 caring about security"
  href="cgi-security.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node561.html">18.2.4 Old classes</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-cgi.html">18.2 cgi  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="cgi-security.html">18.2.6 Caring about security</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION0020250000000000000000">
18.2.5 Functions</a>
</h2>
<a name="Functions_in_cgi_module"></a>
<p>
These are useful if you want more control, or if you want to employ
some of the algorithms implemented in this module in other
circumstances.

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3816' xml:id='l2h-3816' class="function">parse</tt></b>(</nobr></td>
  <td><var>fp</var><big>[</big><var>, keep_blank_values</var><big>[</big><var>,
                        strict_parsing</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Parse a query in the environment or from a file (the file defaults
  to <code>sys.stdin</code>).  The <var>keep_blank_values</var> and
  <var>strict_parsing</var> parameters are passed to <tt class="function">parse_qs()</tt>
  unchanged.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3817' xml:id='l2h-3817' class="function">parse_qs</tt></b>(</nobr></td>
  <td><var>qs</var><big>[</big><var>, keep_blank_values</var><big>[</big><var>,
                           strict_parsing</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Parse a query string given as a string argument (data of type 
<span class="mimetype">application/x-www-form-urlencoded</span>).  Data are
returned as a dictionary.  The dictionary keys are the unique query
variable names and the values are lists of values for each name.

<p>
The optional argument <var>keep_blank_values</var> is
a flag indicating whether blank values in
URL encoded queries should be treated as blank strings.  
A true value indicates that blanks should be retained as 
blank strings.  The default false value indicates that
blank values are to be ignored and treated as if they were
not included.

<p>
The optional argument <var>strict_parsing</var> is a flag indicating what
to do with parsing errors.  If false (the default), errors
are silently ignored.  If true, errors raise a <tt class="exception">ValueError</tt>
exception.

<p>
Use the <tt class="function"><tt class="module"><a href="module-urllib.html">urllib</a></tt>.urlencode()</tt> function to convert
such dictionaries into query strings.

<p>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3818' xml:id='l2h-3818' class="function">parse_qsl</tt></b>(</nobr></td>
  <td><var>qs</var><big>[</big><var>, keep_blank_values</var><big>[</big><var>,
                            strict_parsing</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Parse a query string given as a string argument (data of type 
<span class="mimetype">application/x-www-form-urlencoded</span>).  Data are
returned as a list of name, value pairs.

<p>
The optional argument <var>keep_blank_values</var> is
a flag indicating whether blank values in
URL encoded queries should be treated as blank strings.  
A true value indicates that blanks should be retained as 
blank strings.  The default false value indicates that
blank values are to be ignored and treated as if they were
not included.

<p>
The optional argument <var>strict_parsing</var> is a flag indicating what
to do with parsing errors.  If false (the default), errors
are silently ignored.  If true, errors raise a <tt class="exception">ValueError</tt>
exception.

<p>
Use the <tt class="function"><tt class="module"><a href="module-urllib.html">urllib</a></tt>.urlencode()</tt> function to convert
such lists of pairs into query strings.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3819' xml:id='l2h-3819' class="function">parse_multipart</tt></b>(</nobr></td>
  <td><var>fp, pdict</var>)</td></tr></table></dt>
<dd>
Parse input of type <span class="mimetype">multipart/form-data</span> (for 
file uploads).  Arguments are <var>fp</var> for the input file and
<var>pdict</var> for a dictionary containing other parameters in
the <span class="mailheader">Content-Type:</span> header.

<p>
Returns a dictionary just like <tt class="function">parse_qs()</tt> keys are the
field names, each value is a list of values for that field.  This is
easy to use but not much good if you are expecting megabytes to be
uploaded -- in that case, use the <tt class="class">FieldStorage</tt> class instead
which is much more flexible.

<p>
Note that this does not parse nested multipart parts -- use
<tt class="class">FieldStorage</tt> for that.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3820' xml:id='l2h-3820' class="function">parse_header</tt></b>(</nobr></td>
  <td><var>string</var>)</td></tr></table></dt>
<dd>
Parse a MIME header (such as <span class="mailheader">Content-Type:</span>) into a main
value and a dictionary of parameters.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3821' xml:id='l2h-3821' class="function">test</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Robust test CGI script, usable as main program.
Writes minimal HTTP headers and formats all information provided to
the script in HTML form.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3822' xml:id='l2h-3822' class="function">print_environ</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Format the shell environment in HTML.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3823' xml:id='l2h-3823' class="function">print_form</tt></b>(</nobr></td>
  <td><var>form</var>)</td></tr></table></dt>
<dd>
Format a form in HTML.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3824' xml:id='l2h-3824' class="function">print_directory</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Format the current directory in HTML.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3825' xml:id='l2h-3825' class="function">print_environ_usage</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Print a list of useful (used by CGI) environment variables in
HTML.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3826' xml:id='l2h-3826' class="function">escape</tt></b>(</nobr></td>
  <td><var>s</var><big>[</big><var>, quote</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Convert the characters
"<tt class="character">&amp;</tt>", "<tt class="character">&lt;</tt>" and "<tt class="character">&gt;</tt>" in string <var>s</var> to
HTML-safe sequences.  Use this if you need to display text that might
contain such characters in HTML.  If the optional flag <var>quote</var> is
true, the quotation mark character ("<tt class="character">"</tt>") is also translated;
this helps for inclusion in an HTML attribute value, as in <code>&lt;A
HREF="..."&gt;</code>.  If the value to be quoted might include single- or
double-quote characters, or both, consider using the
<tt class="function">quoteattr()</tt> function in the <tt class="module"><a href="module-xml.sax.saxutils.html">xml.sax.saxutils</a></tt>
module instead.
</dl>

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="18.2.4 old classes"
  href="node561.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="18.2 cgi  "
  href="module-cgi.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="18.2.6 caring about security"
  href="cgi-security.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node561.html">18.2.4 Old classes</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-cgi.html">18.2 cgi  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="cgi-security.html">18.2.6 Caring about security</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
